Inside Macintosh: Imaging with QuickDraw
Previous | Chapter Top | Chapter Contents | Next |
Pixel patterns can use colors at any pixel depth and can be of any width and height that's a power of 2. To create a pixel pattern, you typically define it in a 'ppat' resource, which you store in a resource file. To retrieve the pixel pattern stored in a 'ppat' resource, you can use the GetPixPat function.
Color QuickDraw also allows you to create and dispose of pixel patterns by using the NewPixPat , CopyPixPat , MakeRGBPat , and DisposePixPat routines, although generally you should create them in 'ppat' resources (described on The Pixel Pattern Resource ).
When your application is finished using a pixel pattern, it should dispose of it with the DisposePixPat procedure.
To get a pixel pattern ( 'ppat' ) resource stored in a resource file, you can use the GetPixPat function.
FUNCTION GetPixPat (patID: Integer): PixPatHandle;
The GetPixPat function returns a handle to the pixel pattern having the resource ID you specify in the patID parameter. The GetPixPat function calls the following Resource Manager function with these parameters:
GetResource('ppat', patID);
If a 'ppat' resource with the ID that you request does not exist, the GetPixPat function returns NIL .
When you are finished with the pixel pattern, use the DisposePixPat procedure (described on DisposePixPat ).
The GetPixPat function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
The 'ppat' resource format is described on The Pixel Pattern Resource . See the chapter "Resource Manager" in Inside Macintosh: More Macintosh Toolbox for more information about resources, the Resource Manager, and the GetResource function.
Although you should generally create a pixel pattern in a 'ppat' resource and retrieve it with the GetPixPat function, you can use the NewPixPat function to create a new pixel pattern.
FUNCTION NewPixPat: PixPatHandle;
The NewPixPat function creates a new PixPat record (described on PixPat ) and returns a handle to it. This function calls the NewPixMap function to allocate the pattern's PixMap record (described on PixMap ) and initialize it to the same settings as the pixel map of the current GDevice record--that is, as stored in the gdPMap field of the global variable TheGDevice . This function also sets the pat1Data field of the new PixPat record to a 50 percent gray pattern. NewPixPat allocates new handles for the PixPat record's data, expanded data, expanded map, and color table but does not initialize them; instead, your application must initialize them.
Set the rowBytes , bounds , and pixelSize fields of the pattern's PixMap record to the dimensions of the desired pattern. The rowBytes value should be equal to
(width of bounds) ¥ pixelSize /8
The rowBytes value need not be even. The width and height of the bounds must be a power of 2. Each scan line of the pattern must be at least 1 byte in length--that is, ([width of bounds] ¥ pixelSize ) must be at least 8.
Your application can explicitly specify the color corresponding to each pixel value with a color table. The color table for the pattern must be placed in the pmTable field in the pattern's PixMap record.
Including the PixPat record itself, NewPixPat allocates a total of five handles. The sizes of the handles to the PixPat and PixMap records are the sizes of their respective data structures. The other three handles are initially small in size. Once the pattern is drawn, the size of the expanded data is proportional to the size of the pattern data, but adjusted to the depth of the screen. The color table size is the size of the record plus 8 bytes times the number of colors in the table.
When you are finished using the pixel pattern, use the DisposePixPat procedure, which is described on DisposePixPat , to make the memory used by the pixel pattern available again.
Use the CopyPixPat procedure to copy the contents of one pixel pattern to another.
PROCEDURE CopyPixPat (srcPP,dstPP: PixPatHandle);
The CopyPixPat procedure copies the contents of one PixPat record (the handle to which you pass in the srcPP parameter) into another PixPat record (the handle to which you pass in the dstPP parameter). The CopyPixPat procedure copies all of the fields in the source PixPat record, including the contents of the data handle, expanded data handle, expanded map, pixel map handle, and color table.
The PixPat record is described on PixPat .
To create the appearance of otherwise unavailable colors on indexed devices, you can use the MakeRGBPat procedure.
PROCEDURE MakeRGBPat (ppat: PixPatHandle; myColor: RGBColor);
The MakeRGBPat procedure generates a PixPat record that, when used to draw a pixel pattern, approximates the color you specify in the myColor parameter. For example, if your application draws to an indexed device that supports 4 bits per pixel, you only have 16 colors available if you simply set the foreground color and draw. If you use MakeRGBPat to create a pattern, and then draw using that pattern, you effectively get 125 different colors. If the graphics device has 8 bits per pixel, you effectively get 2197 colors. (More colors are theoretically possible; this implementation opted for a fast pattern selection rather than the best possible pattern selection.)
For a pixel pattern, the patMap^^.bounds field of the PixPat record always contains the values (0,0,8,8), and the patMap^^.rowbytes field equals 2.
Because patterns produced with MakeRGBPat aren't usually solid--they provide a selection of colors by alternating between colors, with up to four colors in a pattern-- lines that are only one pixel wide may not look good.
When MakeRGBPat creates a ColorTable record, it fills in only the rgb fields of its ColorSpec records; the value fields are computed at the time the drawing actually takes place, using the current pixel depth for the system.
Use the DisposePixPat procedure to release the storage allocated to a pixel pattern. The DisposePixPat procedure is also available as the DisposPixPat procedure.
PROCEDURE DisposePixPat (ppat: PixPatHandle);